Lip Sync Video

Introduction

Use the Lip Sync API to generate a new video where the speaker’s mouth movement is synchronized to a target audio track. Submit a source video URL and an audio URL, then poll the task status until the final result is ready.

Key Features

Async Processing

Submit once and retrieve results when processing completes

Simple Input

Create tasks with just a video URL and an audio URL

Flexible Playback

Choose how to handle cases where video is shorter than audio

Result Metadata

Get output video URL, cover image, duration, and error details

Workflow Overview

Lip sync video generation is an asynchronous 3-step process:

Submit Task

Call the create endpoint with your source video and source audio URLs

Processing

JoggAI performs lip sync generation in the background

Retrieve Result

Poll the task endpoint until status becomes success or failed

Lip sync generation is asynchronous. After submitting the task, store the returned task_id and use it to poll for progress and results.

Quick Start

Endpoint	Purpose	Documentation
`POST /v2/create_lip_sync_video`	Submit lip sync task	API Reference
`GET /v2/lip_sync_video/{task_id}`	Check lip sync task status	API Reference

Key Parameters

Parameter	Type	Required	Description
`video_url`	string	✅	Publicly accessible source video URL
`audio_url`	string	✅	Publicly accessible source audio URL
`playback_type`	string	❌	Playback behavior when source video is shorter than audio

Playback Type Values

Value	Description
`normal`	Play the source video normally
`normal_reverse`	Alternate forward and reverse playback to extend the video
`normal_reverse_by_audio`	Extend playback dynamically based on source audio duration

Pricing

Rule	Value
Credits per duration	`1` credit per `125` seconds
Approximate cost per second	`0.008` credits/second
Display rule	Round up and keep `2` decimal places

Estimated usage can be calculated from output duration. Since 1 / 125 = 0.008, the displayed unit cost is approximately 0.01 credits per second when rounded up to 2 decimal places.

The video_url and audio_url must be publicly accessible direct URLs. Temporary or authenticated links may fail during processing.

Code Examples

Step 1: Submit Lip Sync Task

curl --request POST \
  --url 'https://api.jogg.ai/v2/create_lip_sync_video' \
  --header 'x-api-key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "video_url": "https://res.jogg.ai/source-video.mp4",
    "audio_url": "https://res.jogg.ai/source-audio.wav",
    "playback_type": "normal"
  }'

Response:

{
  "code": 0,
  "msg": "Success",
  "data": {
    "task_id": "3d5c6930-d0da-4f7b-826e-cd1530f6734f",
    "status": "pending"
  }
}

Save the task_id from the response. You will need it to poll the lip sync task result.

Step 2: Check Task Status

curl --request GET \
  --url 'https://api.jogg.ai/v2/lip_sync_video/3d5c6930-d0da-4f7b-826e-cd1530f6734f' \
  --header 'x-api-key: YOUR_API_KEY'

Response (Processing):

{
  "code": 0,
  "msg": "Success",
  "data": {
    "task_id": "3d5c6930-d0da-4f7b-826e-cd1530f6734f",
    "status": "processing",
    "created_at": 1741500000,
    "completed_at": null,
    "data": null,
    "error": null
  }
}

Response (Success):

{
  "code": 0,
  "msg": "Success",
  "data": {
    "task_id": "3d5c6930-d0da-4f7b-826e-cd1530f6734f",
    "status": "success",
    "created_at": 1741500000,
    "completed_at": 1741500030,
    "data": {
      "result_url": "https://res.jogg.ai/lipsync-result.mp4",
      "cover_url": "https://res.jogg.ai/lipsync-cover.jpg",
      "duration_seconds": 12.5
    },
    "error": null
  }
}

Response (Failed):

{
  "code": 0,
  "msg": "Success",
  "data": {
    "task_id": "3d5c6930-d0da-4f7b-826e-cd1530f6734f",
    "status": "failed",
    "created_at": 1741500000,
    "completed_at": 1741500030,
    "data": null,
    "error": {
      "message": "consume retry limit reached: audio duration fetch failed"
    }
  }
}

Status Values

Status	Description	Action
`pending`	Task has been accepted and queued	Wait, then poll again
`processing`	Lip sync is currently being generated	Continue polling
`success`	Final video is ready	Download `result_url`
`failed`	Task could not be completed	Inspect `error.message`

Poll every 5-10 seconds for active tasks. In production, avoid overly aggressive polling to reduce unnecessary API traffic.

Use Case Examples

Voice replacement workflows

Reuse an existing talking-head video with a different audio track for updated messaging or campaigns.

Batch content localization

Generate multiple lip sync tasks for different audio tracks and languages using the same base video.

Tips for Best Results

Input quality matters:

Use a clear frontal face shot when possible
Avoid heavy occlusion around the mouth area
Use clean audio with stable volume
Prefer publicly accessible CDN URLs over temporary download links

Playback strategy guidance:

Use normal when video duration already matches the audio well
Use normal_reverse when you want a simple loop-like extension effect
Use normal_reverse_by_audio when alignment should adapt to the audio duration

Polling guidance:

Start polling a few seconds after task creation
Poll every 5-10 seconds during active processing
Stop polling once status is success or failed

Troubleshooting

Source URL cannot be fetched

Issue: Task fails because the video or audio file cannot be downloaded.Solutions:

Ensure both URLs are publicly accessible
Avoid signed URLs that expire too quickly
Verify the files are reachable from outside your network
Confirm the linked file is the actual media file, not an HTML preview page

Task remains processing for too long

Issue: Status stays processing longer than expected.Solutions:

Continue polling with a moderate interval
Retry with smaller or simpler media files if needed
Verify source media is stable and downloadable
Contact support if the task remains stuck for an extended period

Create Lip Sync Video Task

Full request schema for submitting tasks

Get Lip Sync Video Task

Full response schema for task status and result

Check Video Result & Status

General guidance for polling asynchronous video tasks

Webhook Integration

Recommended callback pattern for async workflows

QuickStart

Workflows Guides

Video

Avatar

Voice

Asset

Template

Product

User

Webhook

Introduction

Key Features

Async Processing

Simple Input

Flexible Playback

Result Metadata

Workflow Overview

Quick Start

Key Parameters

Playback Type Values

Pricing

Code Examples

Step 1: Submit Lip Sync Task

Step 2: Check Task Status

Status Values

Use Case Examples

Tips for Best Results

Troubleshooting

Create Lip Sync Video Task

Get Lip Sync Video Task

Check Video Result & Status

Webhook Integration

​Introduction

​Key Features

Async Processing

Simple Input

Flexible Playback

Result Metadata

​Workflow Overview

​Quick Start

​Related API Endpoints

​Key Parameters

​Playback Type Values

​Pricing

​Code Examples

​Step 1: Submit Lip Sync Task

​Step 2: Check Task Status

​Status Values

​Use Case Examples

​Tips for Best Results

​Troubleshooting

​Related Documentation

Create Lip Sync Video Task

Get Lip Sync Video Task

Check Video Result & Status

Webhook Integration

Introduction

Key Features

Workflow Overview

Quick Start

Related API Endpoints

Key Parameters

Playback Type Values

Pricing

Code Examples

Step 1: Submit Lip Sync Task

Step 2: Check Task Status

Status Values

Use Case Examples

Tips for Best Results

Troubleshooting

Related Documentation